feat(agent-skills): manage app agent skills from the CLI - #575

Note

Description

Adds agent skills as a first-class CLI resource. Agent skills are app-scoped instruction snippets stored as one markdown file per skill under base44/agent-skills/ (filename = skill name, front-matter description = summary, body = instructions), which agents reference by name through selected_skill_names. The PR introduces base44 agent-skills pull / push, wires skills into project config and the unified deploy flow (pushed before agents so references resolve), and scaffolds an example skill in the backend-and-client template.

Related Issue

None (push confirmation follows the agents-command parity established in #573)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

New agent-skill resource (packages/cli/src/core/resources/agent-skill/)

• schema.ts — Zod schemas for skills (lowercase-hyphenated name, max 64 chars; description max 1024; body max 15000) plus API list/sync response schemas.
• config.ts — markdown file I/O: readAllAgentSkills() parses *.md with the existing front-matter lib; writeAgentSkills() serializes YAML front-matter, skips unchanged files, and deletes local files missing from the remote list.
• api.ts — fetchAgentSkills() and pushAgentSkills(), which reconciles against the remote set (POST new, PUT changed, DELETE remote-only) and returns created/updated/deleted names. It returns early on an empty local list so a project with no skills never wipes remote skills during deploy.
• resource.ts — implements the standard Resource<AgentSkill> interface (readAll / push).

New CLI commands

• base44 agent-skills pull — fetches remote skills and syncs them into agentSkillsDir, reporting written/deleted files.
• base44 agent-skills push — pushes local skills with a destructive-action confirmation (-y/--yes to skip; auto-skipped when non-interactive), matching the agents commands.
• Both registered in program.ts under a new agent-skills command group.

Project config & deploy

• New agentSkillsDir config key (defaults to agent-skills); agentSkills added to ProjectResources/ProjectData and loaded in parallel with the other resources (empty for plugin resource sets).
• deployAll() pushes agent skills immediately before agents; hasResourcesToDeploy() accounts for them.

Agent schema

• selected_skill_names is now a typed, defaulted ([]) field on AgentConfigSchema. selected_workspace_skill_ids (org-shared workspace skills) still passes through untouched via looseObject.

Template & docs

• The backend-and-client template ships a weekly-report.md example skill, referenced from task_manager.jsonc.
• docs/resources.md gains an "Agent skills" section and updated deploy ordering.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

New/updated tests:

• tests/cli/agent-skills_pull.spec.ts — empty remote, outside-a-project failure, successful pull, API error, files written to disk, unchanged skills skipped, in-place update, local deletion.
• tests/cli/agent-skills_push.spec.ts — empty-project guard, outside-a-project failure, create, update + delete reconciliation.
• tests/core/agent-skills_config.spec.ts — parse, write/read round-trip, deletion, missing directory, invalid name, empty body.
• tests/core/project.spec.ts, tests/core/agents-schema.spec.ts, tests/core/agents.spec.ts — config loading, invalid skill file, selected_skill_names parsing and defaults.
• tests/cli/testkit/TestAPIServer.ts — mocks for the agent-skills GET/POST/PUT/DELETE endpoints; new with-agent-skills and invalid-agent-skill fixtures.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

No new runtime dependencies — front-matter, yaml, and globby are already bundled (front-matter is also used by core/project/template.ts). Skills are pushed before agents during deploy so agents referencing a skill by name resolve against skills that already exist remotely. Both pull and push reconcile (each deletes entries missing on the other side), which is why push prompts for confirmation and the pull description calls out that it replaces local files.

_{🤖 Generated by Claude | 2026-07-30 08:31 UTC | 57983f5}